home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / c / pdc / bind / bind.doc < prev    next >
Text File  |  1990-04-19  |  8KB  |  256 lines
  1. Bind - Binding routine builder
  2.  
  3. Overview
  4. --------
  5.  
  6. This program takes a standard .fd (function definition) file and
  7. generates a binding library for the functions defined in the .fd file.
  8. The bindings are generated based on a set of rules for a target compiler
  9. defined in a file called "bindfile".  These rules specifiy which
  10. registers need to be preserved, how the arguments are passed on the
  11. stack, and the syntax to call an assembler and a librarian.
  12.  
  13.  
  14. File Contents
  15. -------------
  16.  
  17.     Bind -- the AutoDoc program
  18.     bind.doc -- this file
  19.     bindfile -- a sample bindfile containing rules for Aztec (small
  20.         code/data and large code/data version) and Lattice.
  21.     midi_lib.fd -- the .FD file for the MIDI Library.  It's included here
  22.            as a sample non-Rom-Kernel library that use to try
  23.            bind on.
  24.     zlib -- simple Amiga object module librarian
  25.  
  26. Usage
  27. -----
  28.  
  29. The syntax for Bind is:
  30.  
  31.     Bind [opts] <.fd file>
  32.  
  33.     <.fd file> - name of the function definition file to use as a
  34.          source.  The ".fd" portion may be left off of the name.
  35.          The output library name is derived from the portion of
  36.          the .fd file to the left of the period (e.g.
  37.          midi_lib.fd will generate midi_lib.lib)
  38.  
  39.     opts:
  40.     -a    generate assembly only
  41.     -c    generate object modules only
  42.     -f<s>    specify alternate bindfile
  43.     -o<s>    specify output library name
  44.     -r<s>    specify rule name
  45.     -w<s>    specify work directory
  46.  
  47.  
  48.  
  49. A library is built by first generating an object module for each binding
  50. routine and an LVO definition module.  Each module is created by writing
  51. an assembly file to the work directory and then assembling it.    Once all
  52. the object modules are generated they are collected into a library.
  53. Temporary files (assembly and object) are deleted from the work
  54. directory as soon as they are no longer needed.  The actual invocations
  55. for the assembler and librarian depend on the selected set of rules.
  56.  
  57. Binding rules are defined in a "bindfile".  By default this file is
  58. called bindfile and resides in the current directory or the s:
  59. directory.  An alternate bindfile may be specified with the -f switch.
  60. A bindfile contains entries for target compilers.  Each entry contains
  61. rule definitions that specify how to build a binding routine for the
  62. target compiler.  The syntax is as follows:
  63.  
  64. <target>:
  65.     <rule key> = <value>
  66.     .
  67.     .
  68.     .
  69.     <rule key> = <value>
  70.  
  71. <target>:
  72.     <rule key> = <value>
  73.     .
  74.     .
  75.     .
  76.     <rule key> = <value>
  77.  
  78.     .
  79.     .
  80.     .
  81.  
  82.  
  83. The target name can contain any name but must not contain embedded
  84. spaces.  It should begin in the first column and be terminated with a
  85. colon.    Target name matching is case insensitive.
  86.  
  87. Rule keys must be preceded with white space and spelled exactly as
  88. follows (case is not significant).  They may be placed in any order
  89. within a rule set.
  90.  
  91.     StackOffset = <offset>
  92.  
  93.     Specifies how many bytes preceded arguments in the stack frame
  94.     when the routine first becomes active.    If nothing is pushed on
  95.     the stack between the arguments and the return location (pushed
  96.     by jsr) then <offset> would be 4.  This depends very heavily on
  97.     how the target compiler calls routines.  The default value is 0.
  98.  
  99.  
  100.     SaveRegs = <register set>
  101.  
  102.     This specifies the registers that the compiler expects to have
  103.     preserved.  Use a standard 68000 MOVEM register set here (e.g.
  104.     d2-d7/a2-a5).  The default is to preserve no registers.
  105.     Currently you are not allowed to preserve D0 or A7 this way.  D0
  106.     is where return values from placed by standard Kernal routines.
  107.     A7 is the stack and is automatically preserved.
  108.  
  109.  
  110.     Assembler = <asm syntax>
  111.  
  112.     Specifies the name of the assembler to use and its syntax.  Two
  113.     string substitutions are performed here.
  114.  
  115.         $a - gets replaced by the name of the assembly file
  116.          generated by bind.
  117.  
  118.         $o - gets replaced by the name of the object module that
  119.          should be produced by the assembler.
  120.  
  121.     (e.g. as $a -o $o)  Bind generates assembly files suffixed with
  122.     .asm and expects object files to suffixed by .o.  These suffixes
  123.     are supplied with the $a and $o string substitutions.
  124.  
  125.     The assembler used should be capable of generating a
  126.     non-zero return code on failure in order to shut down bind.
  127.     Both Aztec's as and MCC's assem behave well.
  128.  
  129.     The assembler is loaded using fexecl() so that the current path
  130.     will be searched in order to find the assembler.
  131.  
  132.     The default is no assembler.  This will not permit you to make
  133.     anything other than assembly files.
  134.  
  135.  
  136.     Librarian = <lb syntax>
  137.  
  138.     Specifies the name of the librarian to use and its syntax.  Two
  139.     string substitutions are performed here.
  140.  
  141.         $l - is replaced by the selected name of the output library.
  142.  
  143.         $o - is replaced by the entire list of object modules to
  144.          place in the library.
  145.  
  146.     (e.g. lb $l $o)  By default bind will generate a library name
  147.     based on the .fd file name (e.g. midi_lib.fd becomes
  148.     midi_lib.lib).    You can select another output library name using
  149.     the -o option.    .lib is not automatically attached to the name;
  150.     you need to specify it.
  151.  
  152.     As with the assembler, the librarian should be capable of
  153.     generating a non-zero return code on failure in order.    Aztec's
  154.     lb utility and zlib both work this way.
  155.  
  156.     The default is no librarian.  This will prevent you from
  157.     going beyond the object module stage.
  158.  
  159.  
  160. Comments may be placed in the bindfile if they are preceeded with a
  161. pound sign (#) in the first column (like makefile comments).  Also,
  162. blank lines are considered comments.
  163.  
  164. There is a sample bindfile contained in the .arc file.
  165.  
  166.  
  167. Work files
  168. ----------
  169.  
  170. Work files are placed in the "work directory".  The work directory is
  171. determined in one of two ways.    If none is specified, the directory
  172. associated with the environment variable CCTEMP is used (this is set by
  173. either the Aztec or the ARP set command).  You may override this by
  174. using the -w switch to specify any directory.  The default is the
  175. current directory.
  176.  
  177. Work files are automatically deleted when they are no longer needed or
  178. when the program fails or is aborted using Control-C.
  179.  
  180.  
  181. The options
  182. -----------
  183.  
  184. -a causes bind to stop after generating the assembly code for the
  185. bindings.  They appear in the work directory.
  186.  
  187. -c causes bind to assemble the modules that it generates but leave just
  188. the object modules without making a library.
  189.  
  190. -f allows you to specify some other file to use as a bindfile.    The
  191. default bindfile may exist in the current directory or in the s:
  192. directory.
  193.  
  194. -o allows you to specify another name for the output library.  The
  195. default is made by replacing .fd in the source file name with .lib.  A
  196. file comment is set for the output library indicating which rules were
  197. used to create it.
  198.  
  199. -r specifies a rule name.  The default is to use the first rule in the
  200. bind file.
  201.  
  202. -w specifies an alternate work directory.
  203.  
  204.  
  205. Tech info
  206. ---------
  207.  
  208. The program was compiled using Aztec C3.4B.  Everything described works.
  209. At the very least this can be used to generate bindings for Aztec (any
  210. model) and Lattice.
  211.  
  212. Compilers that don't use A7 for a stack, don't return values in D0, pack
  213. the arguments in reverse order, or require that the bindings pop
  214. arguments off the stack are not currently supported by Bind.  This may
  215. change if there is demand for this and the appropriate technical data is
  216. available.
  217.  
  218. .fd files are not described in this document.
  219.  
  220.  
  221. zlib
  222. ----
  223.  
  224. This is a quick and dirty means of generating a Lattice (Amiga) object
  225. module library.  These appear to be little more than a concatenation of
  226. the constituent object modules.  So this program simply joins all of the
  227. files specified into one file.    Its syntax is:
  228.  
  229.     zlib <out> <source>...
  230.  
  231. The source code is included.
  232.  
  233. (btw AmigaDOS (or ARP) join command doesn't work since it is limited to
  234. only 10 (I think) files)
  235.  
  236.  
  237. Last words
  238. ----------
  239.  
  240. There were several inspirations for this program.  I was requested to
  241. make an .fd file for the MIDI Library and also someone told me that the
  242. Aztec bindings for the MIDI Library failed with Lattice (mainly because
  243. Lattice expects A6 to be preserved and Aztec doesn't).  Also, I got
  244. tired of waiting for C bindings for C. Heath's ARP library and hopefully
  245. this will speed things along.
  246.  
  247. Bind is copyright 1987 by Pregnant Badger Software, but feel free to
  248. distribute it without profit.
  249.  
  250.     Bill Barton
  251.  
  252.     Bix: peabody
  253.     delphi: bbarton
  254.     plink: peabody
  255.  
  256.